.TH SG_MAP26 "8" "April 2023" "sg3_utils\-1.48" SG3_UTILS
.SH NAME
sg_map26 \- map SCSI generic (sg) device to corresponding device names
.SH SYNOPSIS
.B sg_map26
[\fI\-\-dev_dir=DIR\fR] [\fI\-\-given_is=\fR0|1] [\fI\-\-help\fR]
[\fI\-\-result=\fR0|1|2|3] [\fI\-\-symlink\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
Maps a special file (block or char) associated with a SCSI device
to the corresponding SCSI generic (sg) device, or vice versa.
Can also be given a sysfs file, for example '/sys/block/sda'
or '/sys/block/sda/dev'.
.PP
Rather than map to or from a sg device, the sysfs file name
matching a given device special file (or vice versa) can be
requested. This is done with '\-\-result=2' and '\-\-result=3'.
This feature works on ATA devices (e.g. 'dev/hdc') as well
as SCSI devices.
.PP
In this utility, "mapped" refers to finding the relationship between
a SCSI generic (sg) node and the higher level SCSI device name; or
vice versa. For example '/dev/sg0' may "map" to '/dev/sda'.
Mappings may not exist, if a relevant module is not loaded, for
example. Also there are SCSI devices that can only be accessed via a sg
node (e.g. SAF\-TE and some SES devices).
.PP
In this utility, "matching" refers to different representations of
the same device accessed via the same driver. For example, '/dev/hdc'
and '/sys/block/hdc' usually refer to the same device and thus would
be considered matching. A related example is that '/dev/cdrom'
and '/dev/hdc' are also considered matching if '/dev/cdrom' is a
symlink to '/dev/hdc'.
.PP
Note that this utility requires root permissions to access the storage
device nodes in the /dev directory. The lsscsi utility may be used
instead in many cases, and lsscsi does not require root permission
as it "data\-mines" the sysfs pseudo file system for the information
it needs.
.PP
For notes on bsg and nvme device nodes see the section on
BSG and NVME DEVICES below.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-d\fR, \fB\-\-dev_dir\fR=\fIDIR\fR
where \fIDIR\fR is the directory to search for resultant device special
files in (or symlinks to same). Only active when '\-\-result=0' (the
default) or '\-\-result=2'. If this option is not given and \fIDEVICE\fR is
a device special file then the directory part of \fIDEVICE\fR is assumed.
If this option is not given and \fIDEVICE\fR is a sysfs name, then if
necessary '/dev' is assumed as the directory.
.TP
\fB\-g\fR, \fB\-\-given_is\fR=0 | 1
specifies the \fIDEVICE\fR is either a device special file (when the
argument is 0), or a sysfs 'dev' file (when the argument is 1). The parent
directory of a sysfs 'dev' file is also accepted (e.g.
either '/sys/block/sda/dev' or '/sys/block/sda' are accepted). Usually
there is no need to give this option since this utility first checks for
special files (or symlinks to special files) and if not, assumes it
has been given a sysfs 'dev' file (or its parent). Generates an error
if given and disagrees with variety of \fIDEVICE\fR.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-r\fR, \fB\-\-result\fR=0 | 1 | 2 | 3
specifies what variety of file (or files) that this utility tries to find.
The default is a "mapped" device special file, when the argument is 0.
When the argument is 1, this utility tries to find the "mapped" sysfs node
name. When the argument is 2, this utility tries to find the "matching"
device special file. When the argument is 3, this utility tries to find
the "matching" sysfs node name.
.TP
\fB\-s\fR, \fB\-\-symlink\fR
when a device special file is being sought (i.e. when '\-\-result=0' (the
default) or '\-\-result=2') then also look for symlinks to that device
special file in the same directory.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity, (i.e. debug output).
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.SH BSG and NVME DEVICES
The bsg driver (Block Scsi Generic) presents alternate Unix character devices
of the form: /dev/bsg/<h:c:t:l>. <h:c:t:l> is a 4 element tuple where 'h' is
the host number, 'c' is the controller number, 't' is the target identifier
and 'l' is the LUN (Logical Unit Number). Other than the bsg device names,
each device, once open()\-ed, operates in a similar fashion to a sg device: a
generic interface at the SCSI command level.
.PP
If a bsg device is given to this utility, it will first try to map it to a
SCSI block device. This will either be of the form /dev/sd<letter_s> for a
disk or /dev/sr<number> for a BD/DVD or CD drive. If no match is found, then
a check is made for a SCSI tape drive with a name of the
form /dev/st<number>. If that fails, the mapping to the corresponding sg
device is made. If the \fI\-\-result=2\fR option is given, the block device
and tape davice checks are bypassed and the mapping to the corresponding sg
device is made.
.PP
Note that this utility makes no mapping to a bsg device. That is pretty easy
to establish using the lsscsi utility as the 4 element <h:c:t:l> tuple is
shown at the beginning of each line (by default) and it uniquely identifies
each SCSI device. Each line will also show the primary device name and, if
the \-\-generic option is given, the sg device node.
.PP
Currently NVMe device nodes come in several varieties, block devices of the
form: /dev/nvme<c>n<n>[p<pn>] where <c> is the controller number (starting
at 0), <n> is the namespace identifier (starting at 1), and <pn> is the
partition number (starting at 1). There are two forms of NVMe character
device nodes: one of the form /dev/nvme<c> and the other of the
form /dev/ng<c>n<n> where "ng" is newer and termed as 'nvme-generic' in
the /proc/devices output. This utility identifies but does not map NVMe
devices. Their naming is more consistent so a utility like this is less
needed. Udev might be used to remap the kernel's naming scheme for NVMe,
removing its inherent naming consistency.
.SH NOTES
This utility is designed for the Linux 2.6 (and later) kernel series.
It uses special file major and minor numbers (and whether the special
is block or character) together with sysfs to do its mapping or
matching. In the absence of any other information, device special
files are assumed to be in the '/dev' directory while sysfs is
assumed to be mounted at '/sys'. Device names in sysfs are
predictable, given the corresponding major and minor number of
the device. However, due to udev rules, the name of device
special files can be anything the user desires (e.g. '/dev/sda'
could be named '/dev/my_boot_disk'). When trying to
find a resultant device special file, this utility uses the major
and minor numbers (and whether a block or char device is sought)
to search the device directory.
.PP
This utility only shows one relationship at a time. To get an
overview of all SCSI devices, with special file names and optionally
the "mapped" sg device name, see the lsscsi utility.
.PP
Even though lsscsi is a functional replacement for this utility,
it has been reported that this utility runs faster in systems that
have a lot of disks connected. Theoretically a Linux system may
have up to 16383 SCSI disks connected to it.
.SH EXAMPLES
Assume sg2 maps to sdb while dvd, cdrom and hdc are all matching.
.PP
  # sg_map26 /dev/sg2
  /dev/sdb
.PP
  # sg_map26 /dev/sdb
  /dev/sg2
.PP
  # sg_map26 \-\-result=0 /dev/sdb
  /dev/sg2
.PP
  # sg_map26 \-\-result=3 /dev/sdb
  /sys/block/sda
.PP
  # sg_map26 \-\-result=1 /dev/sdb
  /sys/class/scsi_generic/sg0
.PP
Now look at '/dev/hdc' and friends
.PP
  # sg_map26 /dev/hdc
  <error: a hd device does not map to a sg device>
.PP
  # sg_map26 \-\-result=3 /dev/hdc
  /sys/block/hdc
.PP
  # sg_map26 \-\-result=2 /dev/hdc
  /dev/hdc
.PP
  # sg_map26 \-\-result=2 \-\-symlink /dev/hdc
  /dev/cdrom
  /dev/dvd
  /dev/hdc
.PP
  # sg_map26 \-\-result=2 \-\-symlink /sys/block/hdc
  /dev/cdrom
  /dev/dvd
  /dev/hdc
.SH EXIT STATUS
The exit status of sg_map26 is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2005\-2023 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B udev(7), lsscsi(lsscsi)
